home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Periodicals / develop / develop 5 code / Lisp Mini-App / Instructions < prev   
Encoding:
Text File  |  1992-04-08  |  12.2 KB  |  301 lines  |  [TEXT/CCL2]
  1. Ruben Kleiman's Mini-Application
  2.  
  3. Instructions
  4. ============
  5.  
  6. Last edit 3/12/92 slm.
  7.  
  8.  
  9. Introduction.
  10.  
  11.    The Mini-Application is a small application designed as a tutorial
  12.    in Macintosh Common Lisp version 2.0; it is intended to accompany
  13.    the article in D e v e l o p magazine (see the file "About Mini-App").
  14.  
  15.    Full documentation can be found in file "All about the Mini-App";
  16.    it is not necessary to read the develop article. 
  17.  
  18.    The Mini-Application is an "application" in the sense that it is a
  19.    complete program that does something specific. A "stand-alone
  20.    application" can be created via MCL's "save-application" function.
  21.    
  22.    This file supersedes files "READ ME FIRST.mw", and 
  23.    "READ ME FIRST.word" by Ruben Kleiman 10/25/90, which contained
  24.    the same text, saved in MacWrite and Word format, respectively.
  25.    (Note that a totally different file "Read Me First.lisp" was 
  26.    apparently distributed under the name "example.lisp").
  27.  
  28.    As far as possible, Ruben's original text has been preserved. The
  29.    section "How This Example Works" from the file "example.lisp" has
  30.    been merged in ("example.lisp" is superseded - see "About Mini-App").
  31.  
  32.    Please read the following before trying out the Mini-Application.
  33.  
  34.  
  35. What is the Mini-Application?
  36.  
  37.    The Mini-Application is a program written by Ruben Kleiman intended
  38.    to be a straightforward and clear tutorial of the user interface and
  39.    language capabilities of Macintosh Common Lisp 2.0.  
  40.  
  41.    It is organized as a core technology, with a sample application
  42.    that runs on top of it. The core, comprising most of the files in
  43.    the "Program" subfolder, implements all the requisite classes, their
  44.    default behavior and the application's menubar and menus. The 
  45.    application, file "mini-app-example.lisp" contains the palette item
  46.    instances and their specialized behavior. 
  47.  
  48.    The core, if loaded with a null application, does nothing useful.
  49.    When the application is loaded on top of the core, various types
  50.    of tools and drawing items will appear in the tool palette.   
  51.  
  52.    Although not intended as an end-user application, you can build
  53.    windows on which you can draw, manipulate, and script a variety of
  54.    objects (e.g., ovals, rectangles, editable text boxes, pictures,
  55.    icons) using a palette and menus in a direct-manipulation style.
  56.  
  57.    Handlers may be defined for classes of or instances of these
  58.    objects, permitting you to associate code with user interface
  59.    behavior (e.g., mouse clicks associated with mouse-down
  60.    event-handling code on a rectangle).  
  61.  
  62.    The application is written to be easily modified and extended
  63.    (many features - e.g., cut/paste, information boxes - are only partly
  64.    implemented to show points of departure where the user may extend
  65.    the code):  the aim is to invite the user to gain expertise in
  66.    Macintosh Common Lisp (Version 2.0) and have some fun.
  67.  
  68.  
  69. Requirements.
  70.  
  71.    You should have the release version of Macintosh Common Lisp 2.0.
  72.  
  73.    MCL2 is available from APDA (see file "Where to buy MCL").
  74.    The Mini-app will not work with earlier versions such as 2.0b1. 
  75.    The Mini-app is unlikely to work with later versions without adjustment. 
  76.  
  77.    4MB of application space is recommended, although a minimal MCL
  78.    configuration is sufficient to run the Mini-Application.
  79.  
  80.  
  81. Installing the Mini-Application.
  82.  
  83.    Make sure the Mini-Application folder is in the same folder
  84.    as the MCL2 application, and is named "Mini-Application".
  85.  
  86.    To load MCL, double-click on the MCL application icon.
  87.  
  88.  
  89. Running the Mini-Application.
  90.  
  91.    To try out the Mini-Application, simply load it as follows:
  92.  
  93.         Choose Load... in the Eval Menu, and
  94.         load file "build-and-run-mini-app.lisp",
  95.  
  96.              or evaluate the following in the Listener:
  97.  
  98.     (load "ccl:Mini-Application;build-and-run-mini-app.lisp")
  99.  
  100.         Note that CLTL2's host syntax (and hence MCL2's syntax) results 
  101.         in the colon and period in the pathname being swapped
  102.         relative to their positions in MCL 2.0b1. If you are not 
  103.         familiar with this syntax see the File System chapters in the
  104.         MCL2 Reference and CLTL2.
  105.  
  106.  
  107. Switching between the Mini-Application and MCL2.
  108.  
  109.    From the Mini-Application to switch back to MCL2's menus:
  110.      - choose Quit in the File menu, or 
  111.      - choose Go To Lisp Menubar in the Options menu.
  112.    To switch back to the Mini-Application:
  113.      - choose Go To Mini-Application in the Tools menu.
  114.      - evaluate (show-menus), or if you've made changes
  115.      - evaluate (load "ccl:Mini-Application;build-and-run-mini-app.lisp")
  116.  
  117.    Note that clicking the Quit tool icon in the Mini-Application's Tools
  118.       palette allows you to quit the Mini-Application AND MCL2.
  119.  
  120.  
  121. Modifying the Mini-Application.
  122.  
  123.    The Mini-Application was designed as a working application to be 
  124.    incrementally modified by the reader interested in self-directed
  125.    learning.
  126.  
  127.    File open-all-text-files.lisp has been added. It defines a new
  128.    Fred command meta-a that opens all text files in a specified
  129.    directory. This is very useful for opening all the program files
  130.    at once when browsing.
  131.  
  132.    In addition to the List Definitions menu item mentioned in the
  133.    article, don't forget to use "meta-point" to help you while browsing:
  134.    put the insertion bar in a function, class or global variable name,
  135.    hold down the option key, and type period. This will bring up the
  136.    definition.
  137.  
  138.  
  139. How the Mini-Application works.
  140.  
  141.    This example of the use of the core functionality of the
  142.    mini-application code supports the creation of a palette containing
  143.    draw-items and tools. A palette carries the tools and draw-items.
  144.    This is just one example of how the Mini-Application core code may
  145.    be built upon.   
  146.  
  147.    The user creates a tool palette by selecting the "Palette" menu item
  148.    in the "Options" menu. The user can create any number of windows by
  149.    choosing "New" from the "File" menu and place items from the palette
  150.    on them.  
  151.  
  152.  
  153. The Mini-Application Tool Palette.
  154.  
  155.    The first two items are icons:
  156.        - the Browse-mode tool icon, and
  157.        - the Quit tool icon.
  158.  
  159.    The following items are "draw-items" and are, in descending order:
  160.        - round button
  161.        - radio button
  162.        - check box
  163.        - text field
  164.        - rectangle (QuickDraw)
  165.        - oval (QuickDraw).
  166.  
  167.    Clicking on the Browse-mode tool toggles between Browse mode and 
  168.       Authoring modes for ALL "draw-dialog" windows.
  169.       In Browse mode you can manipulate the top window in the usual way,
  170.          but you cannot make changes to its contents. More importantly, 
  171.          scripts you attach to draw-items will only run when in Browse mode.
  172.       In Authoring mode you can change the contents of windows, for example
  173.          by dragging draw-items from the palette onto windows (see below).
  174.  
  175.       Note that each mini-application window may, independently of the 
  176.       others, be in either authoring or browse mode. Note that each new 
  177.       window comes up in Authoring mode, and clicking on the Browse-mode
  178.       tool TOGGLES the mode of all windows.
  179.  
  180.    Clicking on the the Quit icon quits the Mini-Application AND MCL.
  181.  
  182.    You may create any number of windows using the "New" menu item in
  183.       the "File" menu.  You can click on any draw-item in the palette
  184.       and drag it out and drop it onto any window.  This will create a
  185.       clone of that draw-item on that window.  You may drag a draw-item
  186.       within a window or from window to window. You may resize a
  187.       draw-item by grabbing one of its corners or sides (no handles
  188.       show in this implementation: exercise for the reader!) - resizing
  189.       appears in reverse video. 
  190.    You can create draw-items of any kind on a window:
  191.       - Select Rectangle Style:
  192.            Click on a palette draw-item to choose that tool. 
  193.            Then click and drag out a rectangle in a window where you
  194.            want a draw-item of that type to appear. A draw-item of
  195.            the appropiate size and kind will be created in the window.
  196.            There is an Options menu menu-item for turning this mode on
  197.            or off for the top window.
  198.       - Click and Drag Style:
  199.            Click and drag on a palette draw-item to drag it out, and
  200.            drops it (by releasing the mouse button) on a window.
  201.            The draw-item will be created at the mouse position where
  202.            the drop occurred and the draw-item will be sized to a 
  203.            standard size (defaults to its size in the palette - there
  204.            is currently no provision to change the default).
  205.            This method of creating draw-items is always available.
  206.  
  207.    When a draw-item is selected, it's type is shown in the title of
  208.       a new menu, prefixed by "Selected:" If the draw-item is in a
  209.       user-created window, its unique system-generated name of the 
  210.       item will be shown after the type.
  211.  
  212.    The Tools palette is not a windoid, which means that if another
  213.       window is active, the Tools palette must be clicked on once to
  214.       activate it, and a second time to choose the tool clicked on.
  215.       For an advanced tutorial on the MCL2 user interface, including
  216.       windoids, study the Interface ToolKit.
  217.  
  218.  
  219. Creating a stand-alone Mini-Application program.
  220.  
  221.    Even when the Mini-Application has just been loaded, there is no
  222.    guarantee you can simply create a standalone application via:
  223.    (save-application "ccl:Mini-Application pgm"), because
  224.    standalone applications must not contain any pointers or handles
  225.    into the Macintosh heap. 
  226.  
  227.    The Mini-Application example program mini-app-example.lisp calls
  228.    function create-tool to create a browse-tool and a quit-tool as it
  229.    loads. Each contains a handle to its icon. create-tool (defined in
  230.    draw-item-class.lisp) calls create-draw-item, which in turn 
  231.    originally called get-resource-handle, (defined in utilities.lisp)
  232.    which returns the handle to the icon. This has been changed so
  233.    get-resource-handle is not called until the icon is actually
  234.    displayed by view-draw-contents. Currently, view-draw-contents
  235.    opens the resource file each time; the reader can optimize this
  236.    to speed icon redraw.
  237.  
  238.    Anything that points into the Macintosh heap must be deallocated
  239.    before saving the application, and restored on reload. This really
  240.    means that what is pointed to must be removed from the heap, and
  241.    restored on reload. See *save-exit-functions* and def-load-pointers
  242.    in chapter "Snapshots and Application Versions of MCL" in the Reference.
  243.    File "ccl:examples;binhex;binhex.lisp" shows how to include the icons
  244.    in the saved application's resource fork.
  245.  
  246.    Note: save-application takes a few minutes; don't be too impatient
  247.          and reboot your Mac.
  248.  
  249.  
  250. Mini-Application Files.
  251.  
  252.    The Mini-Application core consists of the following files:
  253.  
  254.     globals.lisp
  255.         This includes all global definitions.
  256.  
  257.     utilities.lisp
  258.         This includes miscellaneous utility functions required 
  259.         by the mini application.
  260.  
  261.     draw-dialog-class.lisp
  262.         This defines the main window classes to be
  263.         used by the mini applications, including all
  264.         the handler functionality.  It shows you how
  265.         to handle subviews within the window and
  266.         how to write certain handlers (e.g., mouse
  267.         click events).  There is plenty of room here
  268.         for expansion of the mini application's functionality.
  269.  
  270.     menus.lisp
  271.         This includes all menu, menu item and menubar
  272.         definitions for this application.  This is a good
  273.         place to start looking.  It shows you how to
  274.         create, install and de-install menus and it is
  275.         a good lead-in to the rest of the application.
  276.  
  277.     palette-class.lisp
  278.         This defines some specializations of the
  279.         main window class in order to create palettes.
  280.  
  281.     draw-item-class.lisp
  282.         This defines the functionality of the objects
  283.         which will be drawn within windows (e.g.,
  284.         ovals).  It includes dragging, resizing and
  285.         moving code.  The classes for all the predefined
  286.         draw-items are here.
  287.  
  288.     default-handlers.lisp
  289.         This includes all the default handlers (i.e., methods)
  290.         for our mini application (e.g., mouse-up, mouse-down).
  291.         You could improve it by adding more default
  292.         functionality (e.g., you might want to add a hilighting
  293.         capability to the button draw-item's mouse-down
  294.         handler).
  295.  
  296.    Individual files are compiled the first time they are loaded, and
  297.    thereafter whenever they are loaded and their source has changed.
  298.  
  299. end of file Instructions
  300. -----------------------------------------
  301.